docs: add data migration scripts section

Author: leobenzol

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

@@ -103,6 +103,50 @@ So, always rollback the migration before deleting it.
 
 ---
 
+## Data Migration Scripts
+
+Some features might require data migrations to ensure new functionality works as expected after an upgrade. Typically, these migrations can be dealt with by database migrations within a module. However, this is not the case when the changes affect the data models in several modules or if the data is stored in a third-party system. In those scenarios, the data needs to be brought to the desired state.
+
+To do so, you can use data migration scripts. They are very similar to regular scripts, in the sense that you have access to the dependency container, i.e. all modules. However, instead of running manually, data migration scripts are run automatically as part of running `medusa db:migrate`.
+
+### How they work
+
+The Medusa project, its plugins, and the core are scoured for files in the `src/migration-scripts` folder, which are then executed. The files should export a default function. These scripts are only run once, provided they succeed.
+
+The flow is as follows:
+
+- Find files
+- Ensure the `script_migrations` table exists. If not, create it
+- Identify pending migration scripts (scripts that have not been ran previously)
+- Acquire a lock on the table
+- Begin loop, for each script
+  - Insert migration script in the database
+  - Execute script
+  - Mark script as finished
+- Release lock
+
+### Example
+
+```ts title="src/migration-scripts/example.tsx"
+import { MedusaModule } from "@medusajs/framework/modules-sdk"
+import { ExecArgs } from "@medusajs/framework/types"
+import { Modules } from "@medusajs/framework/utils"
+
+export default async function migrationScript({
+  container,
+}: ExecArgs) {
+  // Check if the required modules are present
+  if (!MedusaModule.isInstalled(Modules.PRODUCT))
+    return
+  
+  // Migrate data
+  await migrateDataWorkflow(container).run(...)
+
+}
+```
+
+---
+
 ## More Database Commands
 
 To learn more about the Medusa CLI's database commands, refer to [this CLI reference](!resources!/medusa-cli/commands/db).