docs: add design-rationale commentary to core support classes

Enriches class-level docblocks and inline comments across the shared
utility classes with the "why" behind design decisions that aren't
obvious from reading the code alone:

- Cache       two-tier rationale, atomic-write semantics, failure modes
- Curl        single-use-per-instance rationale, default option choices
- Log         wrapper rationale, redaction expectations for callers
- Database    auto-migration philosophy, schema-versioning approach
- ServerResource  flat-array rationale, interfaces[0]-only limit called
              out for future maintainers, unit-conversion map
- ConfigureService  why a sibling of ModuleFunctions, catalogue caching
              policy, cp-in-constructor reasoning

Pure documentation — no code changes, all files remain lint-clean and
Pint-formatted.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

modules/servers/VirtFusionDirect/lib/Log.php

@@ -3,18 +3,46 @@
 namespace WHMCS\Module\Server\VirtFusionDirect;
 
 /**
- * Thin wrapper around the WHMCS logModuleCall() function for module-level logging.
+ * Thin wrapper around the WHMCS logModuleCall() function.
+ *
+ * WHY A WRAPPER
+ * -------------
+ * Consolidating log writes lets us:
+ *   - Pin the module name in one place (the LOG_MODULE constant). All entries
+ *     go under "VirtFusionDirect" regardless of which caller inserted them,
+ *     which keeps WHMCS Admin → Utilities → Logs → Module Log filterable.
+ *   - Get a stable import path for every file that logs (Log::insert).
+ *   - Add cross-cutting policy later (e.g. redaction, sampling) without
+ *     touching every call site.
+ *
+ * OUTPUT SURFACE
+ * --------------
+ * Entries appear in WHMCS Admin → Utilities → Logs → Module Log. The request
+ * and response parameters accept strings OR arrays — WHMCS serialises arrays
+ * to readable form automatically. Pass structured data (["zone" => $z, "ip" => $ip])
+ * rather than string-concatenated messages; the UI renders arrays as key/value
+ * pairs which makes filtering and debugging much easier.
+ *
+ * REDACTION EXPECTATION
+ * ---------------------
+ * Callers are responsible for not passing secrets into logs. In particular:
+ *   - Never log Authorization/X-API-Key headers
+ *   - Never log full request_header info from the Curl class
+ *   - Never log the decrypted VirtFusion bearer token or PowerDNS API key
+ * The Curl class deliberately defaults CURLOPT_HEADER to off so header capture
+ * doesn't accidentally populate a field that callers might log.
  */
 class Log
 {
+    /** Keep this in sync with the WHMCS server module name, so filters work. */
     const LOG_MODULE = 'VirtFusionDirect';
 
     /**
      * Write an entry to the WHMCS module log.
      *
-     * @param  string  $action  Name of the action being logged (e.g. 'CreateAccount')
-     * @param  string|array  $requestString  Request data sent to the API
-     * @param  string|array  $responseData  Response data received from the API
+     * @param  string  $action  Short tag identifying the operation (used as the "Function" column in the log UI)
+     * @param  string|array  $requestString  Outbound payload or context data. Arrays preferred — rendered as key/value pairs.
+     * @param  string|array  $responseData  Inbound response or result. Same conventions as $requestString.
      */
     public static function insert($action, $requestString, $responseData)
     {