Update documentation and examples, add new nominal accounts features and authentication methods

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

examples/01_baas_flow.php

@@ -6,24 +6,30 @@ use Apoloz\AlfaBank\AlfaBank;
 use Apoloz\AlfaBank\Enums\Environment;
 
 // 1. Initialize
-// Ensure you have valid certificates for the Sandbox
+// CERTIFICATES:
+// - Sandbox: Provided by bank via email or portal (often a .pfx or zip).
+// - Production: Generated by YOU (openssl), public part sent to bank for activation.
 $baas = AlfaBank::baas(
     certificatePath: __DIR__ . '/certs/client.cer',
     privateKeyPath: __DIR__ . '/certs/private.key',
     environment: Environment::SANDBOX,
-    caBundlePath: __DIR__ . '/certs/russian_trusted_sub_ca.crt' // Mincifry
+    caBundlePath: __DIR__ . '/certs/russian_trusted_sub_ca.crt' // Optional: for trusted chain validation
 );
 
 try {
     echo "Authenticating...\n";
     
+    // AUTHENTICATION:
+    // client_id: From Developer Portal (App Settings)
+    // client_secret: From Developer Portal (App Settings -> Key Icon) OR generated via SDK (examples/14_generate_client_secret.php)
+    
     // METHOD A: Standard Client Credentials (for simple services)
     // $baas->login(
-    //    clientId: 'your-client-id',
-    //    clientSecret: 'your-client-secret'
+    //    clientId: 'your-client-id-uuid',
+    //    clientSecret: 'your-client-secret-string'
     // );
     
-    // METHOD B: Authorization Code Flow (H2H) (for Nominal Accounts)
+    // METHOD B: Authorization Code Flow (H2H) (REQUIRED for Nominal Accounts)
     // See examples/13_h2h_auth_service.php for the full setup
     $auth = \Apoloz\AlfaBank\AlfaBank::auth(
         clientId: 'your-client-id',