📄 Add seller status filter documentation

Author: danieldudzic

docs/seller-status-filter.md

@@ -0,0 +1,71 @@
+# Seller Status Filter
+
+## Overview
+The `SellerStatusFilter` allows overriding the PayPal merchant-integrations API response. This is useful when the API is unavailable (e.g., Stage environment returning 404) or when testing specific feature eligibility.
+
+## Hook
+```php
+do_action( 'woocommerce_paypal_payments_seller_status_filter_init', SellerStatusFilter $filter );
+```
+Fires once when the `api.seller-status-filter` container service is resolved.
+
+## API
+
+| Method | Description |
+|---|---|
+| `set_fallback( SellerStatus $status )` | Base response when API fails |
+| `add_product_capability( string $product, string $cap )` | Add capability to a product (auto-creates product if missing) |
+| `remove_product_capability( string $product, string $cap )` | Remove capability from a product |
+| `remove_product( string $name )` | Remove entire product |
+| `ensure_capability( string $name, string $status )` | Ensure top-level capability exists (default: `ACTIVE`) |
+| `remove_capability( string $name )` | Remove top-level capability |
+| `override_country( string $country )` | Override merchant country |
+
+All operations are additive — multiple callers can modify the same product without conflict.
+
+## Examples
+
+### Fallback + ACDC + Vaulting (Stage environment)
+```php
+add_action( 'woocommerce_paypal_payments_seller_status_filter_init', function ( $filter ) {
+    $filter->set_fallback( new SellerStatus( array(), array(), 'US' ) );
+
+    $filter->add_product_capability( 'PPCP_CUSTOM', 'CUSTOM_CARD_PROCESSING' );
+    $filter->ensure_capability( 'CUSTOM_CARD_PROCESSING' );
+
+    $filter->add_product_capability( 'ADVANCED_VAULTING', 'PAYPAL_WALLET_VAULTING_ADVANCED' );
+    $filter->add_product_capability( 'PPCP_CUSTOM', 'PAYPAL_WALLET_VAULTING_ADVANCED' );
+    $filter->ensure_capability( 'PAYPAL_WALLET_VAULTING_ADVANCED' );
+} );
+```
+
+### Inject a single feature
+```php
+add_action( 'woocommerce_paypal_payments_seller_status_filter_init', function ( $filter ) {
+    $filter->add_product_capability( 'PAYMENT_METHODS', 'GOOGLE_PAY' );
+    $filter->ensure_capability( 'GOOGLE_PAY' );
+} );
+```
+
+### Remove a feature
+```php
+add_action( 'woocommerce_paypal_payments_seller_status_filter_init', function ( $filter ) {
+    $filter->remove_product_capability( 'PPCP_CUSTOM', 'CUSTOM_CARD_PROCESSING' );
+    $filter->remove_capability( 'CUSTOM_CARD_PROCESSING' );
+} );
+```
+
+## Feature-to-capability reference
+
+| Feature | Product | Product capability | Top-level capability |
+|---|---|---|---|
+| ACDC | `PPCP_CUSTOM` | `CUSTOM_CARD_PROCESSING` | `CUSTOM_CARD_PROCESSING` |
+| Vaulting | `ADVANCED_VAULTING`, `PPCP_CUSTOM` | `PAYPAL_WALLET_VAULTING_ADVANCED` | `PAYPAL_WALLET_VAULTING_ADVANCED` |
+| Apple Pay | `PAYMENT_METHODS`, `PPCP_CUSTOM` | `APPLE_PAY` | `APPLE_PAY` |
+| Google Pay | `PAYMENT_METHODS`, `PPCP_CUSTOM` | `GOOGLE_PAY` | `GOOGLE_PAY` |
+| APMs | `PPCP_STANDARD` | `PAYPAL_CHECKOUT_ALTERNATIVE_PAYMENT_METHODS` | `PAYPAL_CHECKOUT_ALTERNATIVE_PAYMENT_METHODS` |
+| Fastlane | `PPCP_CUSTOM` | `FASTLANE_CHECKOUT` | `FASTLANE_CHECKOUT` |
+| Venmo | `PPCP_CUSTOM` | `VENMO_PAY_PROCESSING` | `VENMO_PAY_PROCESSING` |
+| Installments | — | — | `INSTALLMENTS` |
+| Crypto | — | — | `CRYPTO_PYMTS` |
+| PUI | `PAYMENT_METHODS` | `PAY_UPON_INVOICE` | — |