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/Import/ImportService.php

@@ -9,6 +9,23 @@ use MintyPHP\Service\Import\Profile\ImportProfileInterface;
 use MintyPHP\Service\Settings\SettingsDefaultsGateway;
 use MintyPHP\Service\Tenant\TenantScopeService;
 
+/**
+ * Orchestrates CSV imports through a three-phase workflow:
+ *
+ *   1. analyzeUpload() — validates file, detects delimiter/headers, stores temp file,
+ *      returns a session-scoped token for subsequent calls.
+ *   2. preview()       — maps columns → target fields, validates each row via the
+ *      profile's dryRunRow(), returns would-create/skip/fail counts.
+ *   3. commit()        — identical mapping + validation, then commitRow() for real
+ *      writes; wrapped in an audit run (start → finish).
+ *
+ * Import behavior is pluggable via ImportProfileInterface. Each profile defines
+ * allowed/required target fields, validation rules, and the actual create logic.
+ * The PROFILE_PERMISSION_MAP links profile keys to the required permission.
+ *
+ * Cross-user token reuse is prevented by verifying user_id in preview/commit.
+ * Assignment columns (tenant/role/department) require a separate permission check.
+ */
 class ImportService
 {
     private const MAX_ROWS = 20000;