add tenant resolution and multi-tenant subdomain info. (#578)

* add tenant resolution and multi-tenant subdomain info.

* address PR comments

network/stellar-disbursement-platform/admin-guide/deploy-the-sdp.mdx

@@ -38,6 +38,14 @@ curl -O https://raw.githubusercontent.com/stellar/stellar-disbursement-platform-
 
 You can find the full list of configurable values in the [SDP GitHub repository](https://github.com/stellar/stellar-disbursement-platform-backend/blob/develop/helmchart/sdp/README.md#stellar-disbursement-platform-sdp-parameters).
 
+There is a more detailed explanation of how to configure the SDP in the [Configuring the SDP Guide](configuring-sdp).
+
+### Multi-tenant considerations
+
+When running the SDP in a multi-tenant configuration, you will need to acquire wildcard TLS certificates to facilitate tenant provisioning as the SDP relies on subdomains to differentiate between tenants. This will allow you to provision tenants without having to manually configure TLS certificates for each tenant. You can use a service like [Let's Encrypt](https://letsencrypt.org/) or [Namecheap](https://www.namecheap.com/security/ssl-certificates/) to acquire these certificates.
+
+For more information about multi-tenancy in the SDP, see the [Design and Architecture Guide](design-and-architecture#multi-tenancy).
+
 ### Install the chart
 
 To install the chart with the release name `sdp` and the values file `myvalues.yaml`:

network/stellar-disbursement-platform/admin-guide/design-and-architecture.mdx

@@ -37,4 +37,27 @@ There are 3 types of schemas in the database:
 
 - **Admin Schema**: contains tables for managing tenants. This schema is used by the Admin API to manage tenant configuration and provisioning.
 - **TSS Schema**: contains tables for managing transactions. This schema is used by the Transaction Submission Service to manage the state of payment transactions.
-- **Tenant Schemas**: each tenant has its own schema that contains tables for managing disbursements, recipients, and other tenant-specific data. These schemas are prefixed with `sdp_`.
+- **Tenant Schemas**: each tenant has its own schema that contains tables for managing disbursements, recipients, and other tenant-specific data. These schemas are prefixed with `sdp_`.
+
+## Multi-tenancy {#multi-tenancy}
+
+The SDP can be deployed in a multi-tenant configuration, where multiple organizations share the same instance of the SDP. Each organization is referred to as a tenant and has its own set of data and configuration. A host organization can manage multiple tenants and manage their configuration through the Admin API.
+
+### Tenant Resolution {#tenant-resolution}
+
+The SDP uses a tenant resolution strategy to determine which tenant a request belongs to. Tenant resolution is only required for unauthenticated requests, as authenticated requests include the tenant information already in the JWT token.
+
+- **Header**: the `SDP-Tenant-Name` header is used to specify the tenant name in the request. When present, this header is used to attempt resolving the tenant.
+- **Subdomain**: the SDP can use the subdomain of the request URL to resolve the tenant. For example, `tenant1.sdp.backend.test` would resolve to the tenant `tenant1`.
+
+Resolution priority goes as follows: JWT token (authenticated requests) > Header > Subdomain.
+
+#### Single Tenant Mode {#single-tenant-mode}
+When single tenant mode is enabled using the `SINGLE_TENANT_MODE` environment variable, all tenants will automatically resolve to the default tenant. A default tenant is set by calling the API [`POST /tenants/default-tenant`](../api-reference/resources/default-tenant).
+
+Default tenant is useful for development purposes or when the SDP is used by a single organization. This allows the organization to skip specifying the tenant in every request and simplifies the SDP setup operationally by removing the need of providing wildcard TLS certificates for multi-tenant configurations.
+
+#### Subdomain Resolution {#subdomain-resolution}
+When running the SDP in multi-tenant mode, the SDP uses the subdomain of the request URL to resolve the tenant. For example, `tenant1.sdp.backend.test` would resolve to the tenant `tenant1`. This allows the SDP to differentiate between tenants without requiring the tenant name to be specified in the request.
+
+The subdomain resolution is particularly important for the Wallet Registration process, as the SDP relies on subdomains to differentiate between tenants during the SEP-24 deposit flow. Home domains, which contain the tenant name as a subdomain, are used during the registration process by the SDP to identify the tenant and route the wallet-registration request to the correct tenant context.