docs: improved data model docs (#11884)

* docs: improved data model docs

* fix build errors

www/apps/book/app/learn/fundamentals/data-models/write-migration/page.mdx

@@ -1,32 +1,46 @@
 export const metadata = {
-  title: `${pageNumber} Write Migration`,
+  title: `${pageNumber} Migrations`,
 }
 
 # {metadata.title}
 
-In this chapter, you'll learn how to create a migration and write it manually.
+In this chapter, you'll learn what a migration is and how to generate a migration or write it manually.
 
 ## What is a Migration?
 
-A migration is a class created in a TypeScript or JavaScript file under a module's `migrations` directory. It has two methods:
+A migration is a TypeScript or JavaScript file that defines database changes made by a module. Migrations are useful when you re-use a module or you're working in a team, so that when one member of a team makes a database change, everyone else can reflect it on their side by running the migrations.
+
+The migration's file has a class with two methods:
 
 - The `up` method reflects changes on the database.
 - The `down` method reverts the changes made in the `up` method.
 
 ---
 
-## How to Write a Migration?
+## Generate Migration
 
-The Medusa CLI tool provides a [db:generate](!resources!/medusa-cli/commands/db#dbgenerate) command to generate a migration for the specified modules' data models.
+Instead of you writing the migration manually, the Medusa CLI tool provides a [db:generate](!resources!/medusa-cli/commands/db#dbgenerate) command to generate a migration for a modules' data models.
 
-Alternatively, you can manually create a migration file under the `migrations` directory of your module.
+For example, assuming you have a `blog` Module, you can generate a migration for it by running the following command:
+
+```bash
+npx medusa db:generate blog
+```
+
+This generates a migration file under the `migrations` directory of the Blog Module. You can then run it to reflect the changes in the database as mentioned in [this section](#run-the-migration).
+
+---
+
+## Write a Migration Manually
+
+You can also write migrations manually. To do that, create a file in the `migrations` directory of the module and in it, a class that has an `up` and `down` method. The class's name should be of the format `Migration{YEAR}{MONTH}{DAY}{HOUR}{MINUTE}.ts` to ensure migrations are ran in the correct order.
 
 For example:
 
 ```ts title="src/modules/blog/migrations/Migration20240429.ts"
 import { Migration } from "@mikro-orm/migrations"
 
-export class Migration20240702105919 extends Migration {
+export class Migration202507021059 extends Migration {
 
   async up(): Promise<void> {
     this.addSql("create table if not exists \"author\" (\"id\" text not null, \"name\" text not null, \"created_at\" timestamptz not null default now(), \"updated_at\" timestamptz not null default now(), \"deleted_at\" timestamptz null, constraint \"author_pkey\" primary key (\"id\"));")
@@ -39,9 +53,7 @@ export class Migration20240702105919 extends Migration {
 }
 ```
 
-The migration's file name should be of the format `Migration{YEAR}{MONTH}{DAY}.ts`. The migration class in the file extends the `Migration` class imported from `@mikro-orm/migrations`.
-
-In the `up` and `down` method of the migration class, you use the `addSql` method provided by MikroORM's `Migration` class to run PostgreSQL syntax.
+The migration class in the file extends the `Migration` class imported from `@mikro-orm/migrations`. In the `up` and `down` method of the migration class, you use the `addSql` method provided by MikroORM's `Migration` class to run PostgreSQL syntax.
 
 In the example above, the `up` method creates the table `author`, and the `down` method drops the table if the migration is reverted.