fix: apply pending migrations without version arithmetic

README.md

@@ -24,6 +24,22 @@ mod, err := migrate.ModuleMigrations(&migrate.MigrationOpts{
 
 Register `mod` and optionally `migrate.ModuleAutoMigrate(true)` after the database module.
 
+## Applying pending migrations
+
+`ApplyPendingMigrations(ctx, pendingCount)` returns the number of migrations
+successfully applied, including empty migrations. A count of `0` applies none,
+a negative count applies all pending migrations, and a positive count applies
+at most that many. Reaching the end of pending migrations is successful, even
+when fewer migrations remain than the positive cap. A failure returns the
+successful count so far and the migration/provider error.
+
+Migration versions are identifiers: contiguous numbers, gaps, timestamps, and
+mixed numbering all work without treating a version difference as a count.
+`AutoMigrate` applies all pending migrations when enabled, retains per-migration
+and completion logs with actual version identifiers and successful counts, and
+returns `ErrPendingMigrations` when disabled and newer migrations exist.
+Already-current databases are a no-op in either mode.
+
 ## CLI
 
 Use [migrate/cli](cli) with `appcli` — not the removed `migrate/cmd` package.