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/Access/PermissionService.php

@@ -8,6 +8,18 @@ use MintyPHP\Repository\Access\RolePermissionRepositoryInterface;
 use MintyPHP\Repository\Access\UserRoleRepositoryInterface;
 use MintyPHP\Service\Audit\SystemAuditService;
 
+/**
+ * Central RBAC permission service — resolves and caches permission keys for users.
+ *
+ * Permission resolution: User → Roles (via user_roles) → Permissions (via role_permissions).
+ * The resolved key list is cached in two tiers:
+ *   - API requests (stateless): in-memory array, lives for one request cycle.
+ *   - Web requests: session store, survives across page loads until refresh.
+ * A forced refresh can be triggered by passing $refresh = true to getUserPermissions().
+ *
+ * All permission key constants are defined here as the single source of truth,
+ * referenced by actions, services, policies, and templates.
+ */
 class PermissionService
 {
     private array $apiPermissionCache = [];

lib/Service/Auth/AuthService.php

@@ -14,6 +14,21 @@ use MintyPHP\Service\User\UserTenantContextService;
 use MintyPHP\Session;
 use MintyPHP\Support\Flash;
 
+/**
+ * Orchestrates authentication flows: login, registration, logout, and session refresh.
+ *
+ * Login is a cascading validation — each step must pass before the next is attempted:
+ *   1. Email verification status (unverified → redirect to verification)
+ *   2. Credential check via Auth::login (email + password)
+ *   3. Account active flag
+ *   4. Local password login allowed (at least one tenant permits it)
+ *   5. Permissions loaded + tenant context hydrated into session
+ *   6. At least one active tenant assigned
+ *
+ * Every outcome (success or failure at any step) is recorded as an audit event.
+ * On SSO-initiated login (loginUserById), steps 1-4 are skipped because the IdP
+ * already authenticated the user; steps 5-6 still apply.
+ */
 class AuthService
 {
     public function __construct(
@@ -293,6 +308,14 @@ class AuthService
         $this->systemAuditService->record($eventType, $outcome, $context);
     }
 
+    /**
+     * Re-validates the session against the current DB state.
+     *
+     * Uses an authz_version counter: the DB version is bumped whenever permissions or
+     * tenant assignments change. A mismatch with the session version triggers a full
+     * reload of user data, permissions, and tenant context. This is the mechanism that
+     * makes permission changes take effect without requiring re-login.
+     */
     public function refreshSessionAuthState(int $userId): array
     {
         if ($userId <= 0) {

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;

lib/Service/Tenant/TenantScopeService.php

@@ -7,6 +7,19 @@ use MintyPHP\Repository\Tenant\TenantRepositoryInterface;
 use MintyPHP\Repository\Tenant\UserTenantRepositoryInterface;
 use MintyPHP\Service\Access\PermissionService;
 
+/**
+ * Enforces tenant-boundary access control across the application.
+ *
+ * Core rules:
+ *   - Users with TENANT_SCOPE_GLOBAL permission bypass all tenant checks.
+ *   - canAccess() resolves the resource's tenant IDs, intersects with the user's
+ *     tenant IDs, and grants access only on overlap.
+ *   - In strict mode (default): unscoped resources (no tenant assigned) are denied.
+ *   - In permissive mode: unscoped resources are allowed.
+ *   - Resources whose tenants all became inactive are always denied (not treated as unscoped).
+ *   - mergeTenantIdsPreservingOutOfScope() ensures that a scoped admin cannot
+ *     accidentally remove tenant assignments outside their own scope.
+ */
 class TenantScopeService
 {
     public function __construct(

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(