docs: add class docblocks, business-rule comments, and transaction wrapper

- Add single-line class docblocks to all 59 repository classes and interfaces
  describing scope and responsibility
- Add multi-line docblocks to key services documenting business rules:
  AuthService (6-step login cascade), ImportService (3-phase CSV workflow),
  TenantScopeService (strict/permissive modes), PermissionService (RBAC
  resolution + two-tier caching), UserAccountService (atomicity + audit)
- Add transaction(callable) wrapper to DatabaseSessionRepository to DRY up
  begin/commit/rollback boilerplate

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

lib/Service/User/UserAccountService.php

@@ -10,6 +10,20 @@ use MintyPHP\Repository\User\UserWriteRepositoryInterface;
 use MintyPHP\Service\Audit\SystemAuditService;
 use MintyPHP\Service\Tenant\TenantScopeService;
 
+/**
+ * User account lifecycle: creation, updates, activation, deletion, and self-service profile edits.
+ *
+ * Write operations (createFromAdmin, register) run inside a DB transaction to ensure
+ * atomicity of user record + tenant/role/department assignments. On any failure the
+ * transaction is rolled back and no partial state is left behind.
+ *
+ * Tenant-scoped operations (delete, bulk activate/deactivate) filter UUIDs through
+ * TenantScopeService before executing, so a scoped admin can only affect users
+ * within their own tenant boundary. Self-delete and self-deactivate are always blocked.
+ *
+ * Every state change is recorded via SystemAuditService with before/after snapshots
+ * where applicable (e.g. active flag, locale, theme, primary tenant).
+ */
 class UserAccountService
 {
     public function __construct(