Document typed ORM fields and ModelField deprecation

docs/database/casts.md

@@ -7,7 +7,7 @@ keywords: casts, serialization, model attributes, pydantic, json, orm
 
 # Casts
 
-Casts automatically transform model attribute values when reading from or writing to the database. Annotate a field with the desired type and the ORM handles the conversion transparently.
+Casts automatically transform model attribute values when reading from or writing to the database. Annotate a field with the desired type and the ORM handles the conversion transparently. The optional `Field[T]()` syntax also supports explicit field types.
 
 ## Built-in Casts
 
@@ -152,17 +152,17 @@ class User(Model):
 
 A `NULL` database value will be returned as `time(9, 0, 0)` instead of `None`.
 
-## Custom Casts with `Attribute`
+## Nested Pydantic Models
 
-For complex types — such as embedded value objects — extend `Attribute`. It is a Pydantic `BaseModel` subclass, so fields are validated and the instance is serialized to JSON automatically.
+For embedded value objects, extend Pydantic's `BaseModel` and annotate the ORM field as `address: Address`. Values are reconstructed as Pydantic models when read and serialized to JSON when written.
 
 ### Defining a custom cast
 
 ```python
 from typing import Optional
-from fastapi_startkit.masoniteorm import Attribute
+from pydantic import BaseModel
 
-class Address(Attribute):
+class Address(BaseModel):
     street: Optional[str] = None
     city: Optional[str] = None
     state: Optional[str] = None
@@ -171,7 +171,7 @@ class Address(Attribute):
 
 ### Wiring it to a model
 
-Annotate the field with your `Attribute` subclass:
+Use your Pydantic model as the field type:
 
 ```python
 from fastapi_startkit.masoniteorm import Model
@@ -183,6 +183,12 @@ class User(Model):
     address: Address
 ```
 
+The legacy declaration `address: Address = ModelField()` remains supported.
+`ModelField` is publicly importable from `fastapi_startkit.masoniteorm`, but
+emits a `DeprecationWarning` and is scheduled for removal in **2.x**. Migrate to
+`address: Address`. If you prefer explicit descriptors, import `Field` and use
+`address = Field[Address]()` instead.
+
 The column should be a `text` or `json` column in your migration:
 
 ```python

docs/database/models.md

@@ -11,7 +11,7 @@ Models represent database tables and are the primary interface for reading and w
 
 ## Defining a Model
 
-Extend `Model` from `fastapi_startkit.masoniteorm` and annotate your columns as class-level type hints:
+Extend `Model` from `fastapi_startkit.masoniteorm` and annotate your columns with Python types:
 
 ```python
 from fastapi_startkit.masoniteorm import Model
@@ -234,4 +234,4 @@ class Post(Model):
 
 Relationship declarations are covered in the [Relationships](./relationships) section.
 
-Automatic type coercion and custom value objects are covered in the [Casts](./casts) section.
+Automatic type coercion and custom value objects are covered in the [Casts](./casts) section.